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By Keith Wood 





An HTML Generator 


Use a Delphi Component to Build Your Web Site 


vilding your own World Wide Web (WWW) site can be a daunting task. 
You need to understand HTTP MIME, HTML, and possibly even CGI 
[see the sidebar “Internet Definitions” on page 23]. However, by using the 


encapsulation available in Delphi’s components, you can hide much of this 


complexity from the novice user. 


This article describes a component that 
allows us to generate HTML with a 
Delphi program, without an in-depth 
understanding of HTML. The compo- 
nent, 7H7TMLWryiter, allows values from 
other sources — typically a database — to 
be included in the documents produced, 
creating truly up-to-date pages for display. 


HyperText Markup Language 

HTML is a language that describes how a 
page will be presented. It’s interpreted by 
various browsers that display the page to 
the user. HTML is not WYSIWYG since 
the final display is determined by the 


<html> 

<head> 

<title>Keith Wood's Home Page</title> 

</head> 

<body> 

<hi>Keith Wood's Home Page</h1> 

<hr> 

<p>Welcome to your own home page.</p> 

<p>Text can be easily <strong>highlighted</strong> or 
<i>italicised</i>. Special characters can be inserted : 
&#169;,&AElig;, &eacute;. Lists can be added :</p> 
<ul> 

<li>First list item. 

<li>Second list item. 

<li>Third list item. 

</ul> 

<p>Include an image if you want :<img src="athena. jpg" 
border=0 alt="Demonstration image" align=middle></p> 
<p>Links can also be added. This one 

<a href="sourceb.htm">shows the code that produced 
this</a>.</p> 

</body> 

</html> 


browser. The advantage of this is that 
browsers can be implemented on many dif- 
ferent platforms with various capabilities. 


Let’s discuss the HTML elements that are 
normally implemented on a home page. 


Tags. An HTML document consists of a 
straight text file with markup instruc- 
tions encoded within tags. These tags are 
delimited by angle brackets ( < > ) 
allowing them to be easily identified. 
Each tag has a name indicating its pur- 
pose, and may have one or more attrib- 
utes to control its function. Many tags 
contain text or other tags, and some 
remain empty (i.e. they stand alone). 


To indicate the end of a particular tag, its 
name is enclosed in angle brackets as 
shown above, but with a slash preceding 
the name. An example of a container tag is 
the paragraph marker <p>, which matches 
its closing version, </p>. 


An example of an empty tag is the image 
directive: 


<img ...> 


Figure 1 is a sample HTML document and 


Figure 2 displays its appearance in a browser. 


Head and Body. An HTML document is 
divided into two parts: the ead and 


Figure 1: A sample HTML document. The use of tags makes 
the code easily understandable. The result of this code is 
shown in Figure 2. 


body. Among others, the head contains 
tags that provide information about the 
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= -View - [Keith ¥/ood's Home Page] 
File Options WNavigate Help 


Keith Wood's Home Page 


Welcome to your own home page. 


Text can be easily highlighted or italicised . Special characters can be 
inserted : @), 4 6 Lists can be added : 

® First list item. 

® Second list item. 

® Third list item. 


Tnclide an image if you want 





Figure 2: The visual representation of the HTML code shown in 
Figure 1. The I-View browser is being used to view the page. 


document as a whole, including the document’s title 
and the base URL for this and related documents. The 
title is the only mandatory tag in the header block. An 
example of a document header is: 


<head> 
<title>Keith Wood's Home Page</title> 
</head> 


The body of the document is the part that is displayed 
to the user. It can contain text, images, tables, lists, and 
links to other documents. HTML allows up to six levels 
of headings, <h1> to <h6>, with each heading displayed 
in a slightly different way. HTML also allows text to be 
grouped into paragraphs. Sections of text can be for- 
matted in various ways with physical tags such as <b> 
(for bold) and <i> (for italics), or with logical tags, 
such as <strong> and <code>. How the latter are dis- 
played is determined by the browser. For example: 


<hi>Keith Wood's Home Page</h1> 

<p>Welcome to your own home page.</p> 

<p>Text can be easily <strong>highlighted</strong> or 
<i>italicised</i>.</p> 


Images. Images can be included in the document, with the 
standard formats being X-bitmap, .GIF, and JPEG files. 


For example: 


<img src="athena. jpg" 
align=middle> 


border=0 alt="Demonstration image" 


These can be positioned relative to surrounding text 
and resized if required. A text alternative to images is 


also available for those browsers that cannot handle 
images, or have been disabled by the user to save load 
time. 


Lists. Several styles of lists can be displayed in HTML 
documents, with the main ones being unordered (usual- 
ly displayed with bullets) <ul>, ordered <ol>, and glos- 
sary <d1>, consisting of a series of terms and their defin- 
itions. Some lists can be embedded to create multi-lay- 
ered structures. Here’s an example of an unordered list: 


<ul> 

<li>First list item. 
<li>Second list item. 
<li>Third list item. 
</ul> 


Links. The most important part of an HTML docu- 
ment is its /inks. Using the tag <a>, links provide refer- 
ences to other parts of the same document or related 
documents, which can be anywhere in the world. 


A section of text or an image is marked as the anchor 
(or hotspot) for the link, and is presented to the user in 
some highlighted format. Clicking on an anchor causes 
the browser to request the specified document (identi- 


fied by its URL) from its server and display the results: 


<a href="sourceb.htm">shows the code that 
produced this</a> 


The Table Construct. Some columnar formatting can 
be provided by the table construct, <table>. Tables are 
comprised of rows, <tr>, which are themselves com- 
prised of headings, <th>, or cells, <td>. These headings 
and cells contain text and other HTML tags. The bor- 
ders can be sized or made invisible, and even colored in 
some browsers. Items within headings and cells can be 
aligned both horizontally and vertically. For example: 


<table> 
<tr><th>Column 1</th><th>Column 2</th></tr> 
<tr><td>Cell 1,1</td><td>Cell 2,1</td></tr> 
</table> 


Forms. Forms provide a way for users to interact with 
the document, supplying entered information to the 
server. Normally a CGI program receives the parameters 
and processes them accordingly. This can be used to 
search Web indexes, respond to surveys, or just about 
anything else you can imagine. The processing of CGI 
programs is beyond the scope of this article, but the fol- 
lowing code demonstrates how simple form input capa- 
bility can be implemented: 


<form method=get action="Ssearch"> 

<p>Enter word to search for: <input type=text name="value"> 
<input type=submit name="action" value="Search"></p> 
</form> 


Spacing, etc. Additional spacing within an HTML docu- 


ment is ignored, unless it occurs within a preformatted 
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section. [his means that consecutive spaces, tabs, and car- 
riage returns are all treated as if they were a single space. 
The document's formatting is done by the browser, based 
upon the embedded tags. ‘Tags that are not understood by 
a browser are ignored. This allows new features to be 
added incrementally without adversely affecting existing 
browsers and documents. 


The basic definition of HTML is referred to as version 
2.0. This includes all the basic tags, but excludes tables. 
Further extensions to this standard have been proposed 
and are being finalized into HTML 3.0. These include 
tables, client-side image maps, and common attributes for 
many existing tags. 


In the meantime, various browser providers are including 
non-standard extensions to HTML that work within their 
products. The leading organization in this category is 
Netscape. Their extensions include specifying colors for the 
page background, text and links, centering text and images, 
customizing lists and horizontal rules, etc. Netscape’s other 
principal extensions are tables and background images, 
which have now been included in the proposed HTML 
3.0 standard. Microsoft’s new Internet Explorer has added 
its own extensions, primarily in the area of multimedia. 
(For additional resources see Figure 12.) 


An HTML Writer Component 

The Delphi component that helps us generate HTML is 
THTMLWriter. Since it’s non-visual, it’s derived directly 
from TComponent. Therefore, TH7MLWriter can be 
placed on the Component Palette and easily incorporated 
into our projects. 


THTMLWyriter consists of only four properties and many 
methods to produce the various tags available in HTML. 
The properties are: 

m Filename: The name of the file to which the generated 
HTML is directed. Filename defaults to 
HTMLWRTR.HTM (in Windows, HTML files have the 
-HTM extension). When changed, the previous file is 
closed and the new one is opened, or created, ready for 
output. 

m Errors: We'll discuss the Errors property in “Errors and 
Warning.” 

m LncludeMIME Type: Set to True if the MIME header is 
automatically included in the output. This would nor- 
mally be done if the program is functioning in a CGI 
environment. 

m Version: A read-only property that shows THTMLWyiter's 


current version. 


A Two-Tiered Approach 

To maximize the usefulness of TH7TMLWyiter, we imple- 
ment a two-tiered approach for generating HTML. 
First, there is a set of functions that return string values. 
These correspond to the different HTML tags and allow 
the HTML formatted text to be returned for further 


manipulation in the program. Then a set of procedures 
that correspond to the functions writes the formatted 
text to the output file. 


At each point, appropriate error processing is per- 
formed. In the functions, this relates to mandatory 
attributes and warnings about various HTML exten- 
sions. For the procedures, the error processing involves 
relationships between tags. Note that TH7MLWyiter is 
not intended to support every possible combination of 
tags and attributes, just the most common. Of course, 
you can always extend it. 


Since a container tag can surround an arbitrary number of 
characters, we cannot guarantee that a string value (limited 
to 255 characters) will always satisfy the requirement. Thus 
all such tags come in opening and closing versions, with 
convenient shortcuts for smaller text values. A good exam- 
ple of this is the paragraph tag. A paragraph in HTML 
begins with <p> and ends with </p>. This is implemented 
in the FormatParagraphStart and FormatParagraphEnd 
functions, with the corresponding ParagraphStart and 
ParagraphEnd procedures (see Figure 3). 


The HTML tag is built by the FormatParagraphStart func- 
tion, including the alignment attribute if it’s not the 
default. If the alignment attribute is used and we want to 
be informed about HTML 3.0 extensions, then a warning 
exception is raised. In the corresponding ParagraphStart 
procedure, the value returned above is written to the out- 
put file. The additional code ensures that the tag is not 
being placed in an invalid position in the document, and 
then registers its own presence. 


The s Zags variable is a TStringList containing all the 
opening tags that haven't been closed. This allows for 
warnings to be generated later when tags are closed out 
of sequence. The try..except block ensures that the tag 
is written to the output even when the warning in the 
function is raised. It’s then re-raised to allow the gener- 
ating program to see and handle this exception. 


The ParagraphEnd procedure first checks that the paragraph 
tag is the next one that must be closed — an error is raised if 
it isn't. ParagraphEnd must then remove the tag from the list 
of those open and write the result to the output. Note that 
the ending tag is written followed by an end-of-line, using 
Writeln. Recall that spacing within an HTML document is 
generally ignored and that this is done merely to improve 

the readability of the generated document. Thus, these 
methods allow us to write the following Object Pascal code: 


ParagraphStart(ahDefault) ; 
Text('This text makes up the entire paragraph. '); 
ParagraphEnd; 


which in turn generates this HTML: 


<p>This text makes up the entire paragraph.</p> 
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{ Return start of paragraph as a string. } 
function THTMLWriter.FormatParagraphStart ( 


ahAlign: THTMLAlignHoriz): string; 
begin 
Result := '‘<p'; 


if ahAlign <> ahDefault then 
Result := Result + ‘' align=' 
Result := Result + ‘'>'; 


+ sAlignHoriz[ahAlign] ; 


if (ahAlign <> ahDefault) and (erHTML3 in Errors) then 
raise EHTMLWarning.Create(tcParagraph, 
‘ALIGN is HTML 3.0extension' ,Result) ; 
end; 


{ Write start of paragraph. } 
procedure THTMLWriter.ParagraphStart ( 
ZhAlign: THTMLALignHoriz) ; 
begin 
CheckNesting(tcParagraph,False,True,False, True, True) ; 
sTags.Add('p'); 
try 
Write(fOutput, FormatParagraphStart(ahAlign) ) ; 


except on e: 
begin 
Write(fOutput,e.Result) ; 
raise; 
end; 
end; 
end; 


EHTMLWarning do 


{ Return end of paragraph as string. } 


function THTMLWriter.FormatParagraphEnd: string; 
begin 

Result := ‘</p>'; 
end; 


{ Write end of paragraph. } 

procedure THTMLWriter.ParagraphEnd; 

begin 
CheckClosing(tcParagraph, (sTags.IndexOf('p') 

‘p', ‘paragraph’ ) ; 

sTags.Delete(sTags.Count - 1); 
Writeln(fOutput,FormatParagraphEnd) ; 

end; 


UN s 


Figure 3: Procedures and functions for starting and ending paragraphs. 


To make it easier to create small paragraphs, two extra 
methods are defined: the FormatParagraph function and the 
Paragraph procedure. They combine the paragraph start and 
end methods above with the specified text in between. This 
allows us to generate an entire paragraph in one statement: 


Paragraph('This text makes up the entire paragraph.', 
ahDefault) ; 


Some tags have many attributes, most of which are not nor- 
mally required. To make these tags easier to use, they can be 
invoked in two formats: with all the available parameters 
specified, or with just those parameters that are most com- 
monly used (including none). 


An example of this is the img tag that displays an image in 
the document. In its full format, img takes 10 parameters, 
of which three are common. Thus, one method, 
FormatlmageParams, is defined that takes all the parameters 
and processes those that are not default values. The shorter 
version, Formatlmage, simply calls the full one, passing 
across those parameters that have been supplied and send- 
ing default values for the remainder (see Figure 4). 


Doing it this way means that the actual processing is only 
done in the one place, making maintenance easier, with 
changes to the full version being immediately reflected in 
the shorter version. Other tags that have similar versions 
include the body, the horizontal rule, lists, and tables. 


Another thing to notice about the image processing 
code is the call to the function ChecklfPercentage. This 
is required because an image’s height and width can be 
specified as an absolute value (the actual number of pix- 
els), or as a relative amount (the percentage of the cur- 
rent browser size). To enable the methods to handle 
both cases without additional parameters, we make use 
of the fact that a size must be a positive value. We can 
then flag the fact that a percentage is required by using 


a negative value (with zero indicating that the default 
value be used). 


To avoid having to remember that we must negate the 
value (and to reduce the confusion in the next person that 
has to maintain our code) a function is provided with the 
THTMLWriter component that converts the value for us. 
The Percent function takes a positive integer value and 
returns its negative counterpart. The negative value is then 
decoded in HTML generation and produces the required 


percentage value. 


Thus, we can write the following code to have the image 
fill the entire browser: 


ImageParams('athena.jpg', ‘Athena',EmptyStr,aiDefault, 
Percent(100) ,Percent(100) ,0,0,0,False) ; 


These relative/absolute values are also used in horizontal 
rules, marquees, and tables. 


Colors in HTML are represented differently than those in 
Delphi. To overcome this, the processing converts from 
Delphi 7Color values to a format suitable for HTML. This 
format is #RRGGBB where RAR is the hexadecimal notation 
for the red component, GG for the green, and BB for the 
blue. Thus c/Yellow is converted to the string representa- 
tion '#FFFFOO'. All this is hidden behind the scenes and 
need not concern us. 


Maps 

Another interesting Object Pascal construct arises in the 

generating of areas in an in-line (or client-side) map. An 

area is defined by its shape (rectangle, circle, or polygon) 

and the appropriate coordinates. For example: 

m A rectangle is defined by the x and y coordinates of its 
top-left and bottom-right corners. 

m A circle is defined by the x and y coordinates of the 
center and its radius. 
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{ Return image, with all parameters, as string. } 
function THTMLWriter.FormatImageParams ( 


sImage, sAlt, sMap: string; aiAlign: THTMLAlignImage; 
Height, iWidth: Integer; iHSpace, iVSpace, iBorder: Byte; 
bIsMap: Boolean): string; 

begin 


if (sImage = EmptyStr) and (erErrors in Errors) then 
raise EHTMLError.Create(tcImage, ‘Missing image source' ); 
'" border=' + 


Result := ‘<img src="' + sImage + 


IntToStr(iBorder) ; 


if sAlt <> EmptyStr then 

Result := Result + ‘ alt="' 
if aiAlign <> aiDefault then 

Result := Result + ‘ align=' 
if iHeight <> O then 

Result := Result+CheckIfPercentage( 'height' ,iHeight) ; 
if iWidth <> O then 

Result := Result + CheckIfPercentage('width' ,iWidth) ; 
if iHSpace <> 0 then 

Result := Result + ' 
if iVSpace <> O then 

Result := Result + ' vspace=' + IntToStr(iVSpace) ; 
if sMap <> EmptyStr then 


oy Ve 


+ sAligniImage[aiAlign] ; 


hspace=' + IntToStr(iHSpace) ; 


Result := Result + ' usemap="' + sMap + '"'; 
if bIsMap then 
Result := Result + ' ismap'; 


Result := Result + ‘'>'; 


if ((iBorder<>0) or (iHSpace<>0) or (iVSpace<>0)) and 
(erNetscape in Errors) then 
raise EHTMLWarning.Create(tcImage, 
‘BORDER,HSPACE,VSPACE are Netscape extensions’, 
Result) ; 
if ((iWidth <> 0) or (iHeight <> 0) or 
(aiAlign <> aiDefault) or (sMap <> EmptyStr)) and 
(erHTML3 in Errors) then 


Figure 4: Image processing methods. 


m With a polygon, a list of x and y coordinate pairs define 
the shape, with the last pair combining with the first. 


To handle this in TH7MLW/yiter we need to pass across a 
variable number of parameters. Fortunately, this can be 
done in Object Pascal by declaring the parameter as an 
array of values, integers in this case. Normally an array’s 
size must be declared, but by omitting the array size in the 
declaration, we can pass arrays of different sizes to the one 
routine (provided that the elements are of the correct type): 


iCoords: array of Integer; 

This is known as an open array. We can then process the 
array elements as necessary. Io determine the number of 
elements in the array we use the High function. It returns 
the number of items less one, since the elements are num- 
bered from zero. Figure 5 shows the implementation of 
this construct. Note that this can be extended to cater to a 
variable number of variable type parameters. 


Straight Text 

Straight text can be added to the generated document with 
the Zext method, which simply writes the supplied value 
directly to the file. If the text contains any of the reserved 
characters, then these must be “escaped”, i.e. converted to 


raise EHTMLWarning.Create(tcImage, 
'WIDTH,HEIGHT,ALIGN,USEMAP are HTML 3.0 extensions’, 
Result) ; 
end; 


{ Write image, with all parameters. } 


procedure THTMLWriter.ImageParams(sImage,sAlt,sMap: string; 


aiAlign: THTMLAlignImage; iHeight,iWidth: Integer; 
iHSpace,iVSpace,iBorder: Byte; bIsMap: Boolean) ; 
begin 


CheckNesting(tcImage,False,True,False, True, True) ; 


try 
Write (fOutput , FormatImageParams(sImage,sAlt,sMap, 
aiAlign, iHeight,iWidth,iHSpace, 
iVSpace,iBorder,bIsMap) ) ; 
except on e: EHTMLWarning do 
begin 
Write(fOutput,e.Result) ; 
raise; 
end; 
end; 
end; 


{ Return image as string. } 


function THTMLWriter.FormatImage(sImage,sAlt: string; 
aiAlign: THTMLAlignImage): string; 
begin 


Result := FormatImageParams(sImage,sAlt,EmptyStr,aiAlign, 
0,0,0,0,0,False) ; 
end; 


{ Write image. } 
procedure THTMLWriter.Image(sImage,sAlt: 
aiAlign: 


string; 
THTMLA1lignImage) ; 
begin 
ImageParams(sImage,sAlt,EmptyStr,aiAlign, 
0,0,0,0,0,False) ; 
end; 


non-active values. These characters are the angle brackets 
(< >), ampersand ( & ), and quotation mark ( " ). Two 

methods are provided to perform this: FormatEscape Text, 
which returns the string in escaped form, and Escape Text, 
which writes the escaped text to the file. 


Similarly, lists of strings can be written directly into the 
document or can be escaped first with the 7extList and 
Escape TextList methods. Note that these methods can be 
used to include any HTML constructs that have not been 
covered in the rest of TH7MLWriter. Simply build the 
required syntax in a string (or list of strings) and then 
write it directly into the generated document. 


The /nsertFile method allows large sections of HTML or text 
to be copied into the generated document. No escaping of 
characters is performed by JnsertFile as it is assumed that the 
document has already been processed in this way if necessary. 
This allows common sections of documents to be maintained 
in one place and used by many documents. Note that the file 
is inserted as static text. (We'll discuss allowing for dynamic 
replacement of values in the section, “HTML Templates.”) 


The /nitialise method resets all internal variables that are 
used in checking relationships between tags. This should 
be called before any HTML is generated to ensure that 
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{ Return area for in-line map as string. } 


function THTMLWriter.FormatMapArea(shShape: THTMLShapes; 
iCoords: array of Integer; sUrl,sAlt: string): string; 
var 
i ae Ml aheteve (ede 
sSep string; 
begin 
if erErrors in Errors then 
begin 
i := High(iCoords) + 1; { Num of entries in array. } 
if ((shShape = shRect) and (i<>4)) or 


and (i<>3)) or 


( 
((shShape = shCircle) 
( ((i<6) or Odd(i))) then 


(shShape = shPolygon) and 
raise EHTMLError.Create(tcMap, 
‘Invalid number of coordinates for ‘' + 
sShape[shShape] ) ; 
end; 


Result := '‘<area shape=' + sShape[shShape] ; 
if shShape <> shDefault then 
begin 
sSep := ' coords="'; 
for i := 0 to High(iCoords) do 
begin 
Result := Result + sSep + IntToStr(iCoords[1i]); 
ssep := ','5 
end; 
Result := Result + ‘"'; 
end; 
if sUrl = EmptyStr then 
Result := Result + ' 
else 
Result := Result + ' href="' 
if sAlt <> EmptyStr then 
Result := Result + ' alt="' 
Result := Result + ‘'>'; 
end; 


nohref ' 
+ sUrl oa °""; 


+ sAlt + '"'; 


Figure 5: The FormatMapArea function with an open array 
parameter. 


errors are not introduced from any earlier processing. 
The Finalise method checks that all the open tags have 
been correctly closed, before writing the terminating 
HTML tags (unless a file insertion or merge was per- 
formed) and then closing the output file. Finalise should 
be the last thing called in generating the document. 


Figure 6 presents a complete list of the methods available 
in THTMLWriter. Procedures are listed on the left and 
their corresponding functions (where applicable) are dis- 
played on the right. Each set of procedures and functions 
are grouped by purpose. 


HTML Templates 


In addition to directly generating HTML for our page, 

THTMLWriter can also generate a template document. A 

template is basically just another HTML document, but 

has special tags indicating where variable information 

should be inserted. This replacement is done under pro- 

grammatic control. There are advantages to generating a 

page with a template: 

m= Most of the document can be written directly in 
HTML, making the document easier to maintain, and 
allowing for minor alterations without having to 
recompile the program. 

m The template cleans up the code in the generating pro- 
gram. Instead of describing each line and construct 
individually, the document can be produced with a sin- 


gle method call. 


The implementation of variable tags within a template is 
different than in standard HTML. Braces ( { } ) are 
used to identify these tags, and hold the name of the 
variable whose contents will appear here. For example, 
let’s say a variable name User has been assigned the value 
‘Keith Wood'. Using a template that contains this code: 


<hi>{user}'s Template Demonstration</h1> 


generates this HTML: 


<h1>Keith Wood's Template Demonstration</h1> 


This has been extended to allow for entire files to be insert- 
ed into the template. Follow the opening brace with a caret 
(* ) and the name of the file to be added, and the file will 
be inserted at that point. For example, if the file FOOT- 
ER.FTP contains: 


<hr> 
<p><font size=-1>Generated by the THTMLWriter 
component. </font></p> 


then, a template with the following code: 


<p>The footer for the page comes from another file.</p> 
<p>View the <a href="sourcem.htm">source code 

and templates</a>.</p> 

{*footer.htt} 

</body> 


generates this: 


<p>The footer for the page comes from another file.</p> 
<p>View the <a href="sourcem.htm">source code and 
templates</a>.</p> 

<hr> 

<p><font size=-1>Generated by the THTMLWriter 
component.</font></p> 

</body> 


This technique can be used for common sections of 
HTML, allowing them to be maintained in a single place 
while having their effect apply to the entire site. Examples 
of their use are the body tag, allowing a common color 
scheme to be applied in document footers and in toolbars. 


Both of these replacement strategies are applied recursively. 
This means that a file can be inserted that also contains 
variable tags that are themselves replaced. Similarly, a vari- 
able can be replaced with another variable tag causing dif- 
ferent files to be inserted depending on some condition. 


As a convention, these template files should have an exten- 
sion of .HT'T, to differentiate them from straight HTML 
files (HTM). 


A New Class 


To enable these variables and their values to be speci- 
fied, a new class has been defined in the unit along 
with the TH7MLWyriter component. This is the 
THITMLDictionary class. It’s based on TStringList, but 
adds two new methods. The first is AddFieldAnd Value 
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FormatContent 
FormatHead 
FormatTitle 
FormatlsIndex 


BodyParams 


ee 
ay 
oo 


HorizRuleParams 


WordBreak 


FormatLinkStart 
LinkEnd FormatLinkEnd 


er Sa 
a 


FormatBase 
FormatMeta 


FormatComment 


FormatBodyParams 
FormatBody 
FormatSound 


FormatHeadingStart 
FormatHeadingEnd 
FormatHeading 
FormatParagraphStart 
FormatParagraphEnd 
FormatParagraph 


FormatlmageParams 
Formatlmage 
FormatMapStart 
FormatMapEnd 
FormatMapArea 


FormatListStartParams 
FormatListStart 
FormatListEnd 
FormatListltemParams 
FormatListltem 


FormatHorizRuleParams 
FormatHorizRule 
FormatLineBreak 
Format WordBreak 


TextEffectStart 


Marquee 


Format TextEffectStart 
Format TextEffectEnd 
Format TextEffect 
FormatFontStart 
FormatFontEnd 
FormatFont 
FormatBaseFont 
FormatSpecialChar 
FormatSpecialChar Value 
FormatMarqueeStart 
FormatMarqueeEnd 
FormatMarquee 


Figure 6: The THTMLWriter component's methods. 


Text 

Escape Text 
TextList 
Escape TextList 
InsertFile 
MergeFile 
Initialise 


Finalise 


FormatEscape Text 
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Common Gateway Interface. The standard for 
external gateway programs to interface with 
information servers such as HTTP servers. The 
program should generate an HTML or other 
document for return to the user. 


Graphic Interchange Format, a file format 
standard developed by CompuServe as a 
device-independent method for storing 
images. GIF allows high-quality, high- 
resolution graphics to be displayed on a 
variety of graphics hardware and is intended 
as an exchange and display mechanism for 
graphic images. 


Hyperlext Markup Language. The page 
description language used on the World 
Wide Web. 


HyperText Transfer Protocol. A generic, 
stateless, object-oriented protocol, suitable 
for hypermedia information systems. It’s the 
main protocol for moving HTML and other 
documents around the Web. 


A standard image compression mechanism, 
JPEG (pronounced “jay peg”) is the acronym 
for Joint Photographic Experts Group, the 
original name of the committee that wrote 
the standard. JPEG is designed for compress- 
ing either full-color or gray-scale images of 
natural, real-world scenes. 


Multipurpose Internet Mail Extensions. A 
standard for describing the contents of 
documents transferred through e-mail and 
HTTP. The default type for HTML documents 
is text/html. 


Universal Resource Locator. The address 
of a document, it takes the form: 
//host.domain{:port]/path/document. 


The Windows version of CGI. 


World Wide Web. The hypertext/graphical 
part of the Internet. 


by its name) and its associated value to the list of variables 
to be inserted. AddFieldAndValue is the method used in 
our programs. The other method, GetValue is called dur- 
ing THTMLWyviter’s template processing. Given a field 


name, GetValue returns its corresponding value. If the 


variable does not exist in the dictionary, the variable tag in 
the template is simply deleted. 


The dictionary makes use of the 7StringList’s ability to 
store an associated object with each string. 
Unfortunately, all we want to store is another string, 
but 7StringList is expecting a value derived from 
TObject. One of the ways to overcome this is by defin- 
ing a new class, THTMLFieldValue (derived directly 
from 7Odject), that has a single property which is the 


string we require. 


All this is handled behind the scenes and should not be 
manipulated directly. This allows us to write code similar to 
this example: 





dicDictionary := THTMLDictionary.Create; 
try 
dicDictionary.AddFieldAndValue('user' ,Username2.Text) ; 
with HTMLWriter do begin 
Initialise; 
MergeFile(‘'template.htt' ,dicDictionary) ; 
Finalise; 
end; 
finally 
dicDictionary.Free; 
end; 


Errors and Warnings 

Various errors can occur while generating HTML. These are 
all handled as exceptions within TH7TMLWvriter, allowing us 
to trap, identify, and handle them as necessary. To ease this 
process, a special base exception, FH7MLException, is defined 
in the unit with TH7MLWyiter. The error and warning excep- 
tions, FHTMLError and EHTMLWarning, are then derived 
from EHTMLException. This means that these exceptions can 
be easily identified as having been raised by TH7MLWyiter. 


Each of these exception classes has a Zag property that 
identifies the type of construct that caused the error. These 
are defined by the THTMLTagCategory type and can be 
translated using the 7agCategory array, with Tag as the 
index. Additionally, the FH7MLWarning class has a Result 
property that contains the formatted HTML text for fur- 
ther manipulation within the generating program. 


THTMLWyiter can produce two types of exceptions: errors 
and warnings. Errors are situations that should not be 
ignored, such as missing mandatory values for tags, while 
warnings cover circumstances that may not be what we 
intended. Another major difference in their implementation 
is that when a warning is raised, the original action requested 
is guaranteed to have been completed. This allows the warn- 
ing to be reviewed and processing to continue. (Note that 
not all error conditions are trapped in the TH7MLW/yiter 


component, only those that are most common.) 


Warnings come in four flavors. These are basic warnings, such 
as not having a Submit button on a form, and constructs that 
are HTML 3.0, Netscape, or Microsoft Internet Explorer 
extensions to HTML 2.0. This means that we can check on 
tags that may not be correctly interpreted in various browsers. 


To allow us to control the kind of errors and warnings that 
are generated, THTMLWviter publishes an Errors property, 


which is a set of the different error 





=| Object Inspector | | 
HTML writer!: THT ML Writer =| 


- Errors ferErrors.erv/arnings] 


and warning types described above 


erErrors True 
erv/arnings True 
erNetscape False 


(see Figure 7). Simply include in 
the set those errors and warnings 
that you want to understand. The 
default value is to only be notified Hane 


erlExplorer False 
erHTML3 False 
Filename htrolwrtr. htm 
IncludeMIMEType = True 
HTML riter1 
0 


of errors and basic warnings. Note 
that this set can be empty, mean- 








ing that no errors or warnings are Figure 7: The Delphi 


Object Inspector show- 
ing the nested values 
for the Errors property. 


raised. I suggest that this is done 
only after debugging the generat- 
ing program. 
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Demonstration 

The demonstration project included with this article shows 
some of THTMLWriter's functionality (see Figure 8). It pre- 
sents four options for generating HTML, each of which takes 
a parameter for inclusion in the output. In each case, the 
HTML is written into a predefined file whose name is then 
displayed. This file should then be loaded into your browser 
to view its appearance. Links from these generated pages 
show you the Object Pascal code that produced them using 
the TH7TMLWriter component. If you don't have a browser, 
you can download one (e.g. Netscape); or download I-View 
(a browser intended for use on local documents only); or use 
a Delphi viewer component such as THtmlViewer. 


a THTML Writer Demonstration Mi 
Your name: |Keith Wood 







Your name: [Keith | 


@ HTML has been generated into file BASICS_HTM. 





| Template | 


Information 


Please open this in your viewer. 





Figure 8: The sample application, THTMLWriter Demonstration. 
After entering a value in the Your name field, the user clicks the 
Basics button. An information dialog box appears and instructs 
you to view the updated .HTM file in your browser. 


The basic demonstration shows the variety of constructs 
that can be produced through THTMLWyiter. It 
includes examples of headings, text formatting, images, 
lists, and links. The user’s name, as entered on the 
screen, is inserted into the title and the first heading in 
the document (as is shown in Figure 1). Follow the link 
to see how all this was done. 


The table demonstration asks for the number of columns 
to be generated, between two and five, and then produces 
a table accordingly (see Figure 9). Note that most of the 
table procedure calls use the simplest version, while the 
last table cell requires all the possible parameters to be 
specified so it can be centered across all the columns. 


In the form example (see Figure 10), the various interactive 
controls available in a form are shown. The text entered on 
the screen becomes the default value for the Comments field. 
After entering any values required, you press the Submit but- 
ton to send the form. This one doesn't go anywhere of course, 
but simply calls itself. This should display the parameters 
entered in the Location box at the top of the browser. 


Finally, Figure 11 shows the result of using a template 
for generating HTML documents. The name entered on 
the screen is inserted into the template, along with the 





Netscape - [Table Demonstration Page] 
Bookmarks Options Directory 


Location: |[ER#gAl ib) Meal erde el O ra Wl MO eee ete] od 


El ENG 


Table Demonstration Page 


This page shows how tables can be generated. 


Column 1 
Cell 2,1 
Cell 2,2 


Centred across all columns 


Show the code that produced this. 


Netscape - [Form Demonstration Page] 
File Edit View Go Bookmarks Options Directory 


Form Demonstration Page 


This page shows how forms can be generated. (There is no processing behind this though!) 


Enter your details and press the Submut button. 


Name [i=a=ia= 
(Are you happy? 

Which of the followmg best describes your feelings : 
@ Ecstatic O Just OK © .A bit down 


Pick an activity from the list :|Use Delphi + | 


Keith's Template Demonstration 


This template has had some values inserted into it by the program. These include the current date 
and time, 3/14/96 2:16:46 PM, and arandom number, 1. 


The footer for the page comes from another file. 


View the source code and templates. 


Generated by the THTML Writer component. 


Figure 9 (Top): The table demonstration page showing how the 
cells of an HTML table are formatted. Figure 10 (Middle): The 
form demonstration page with entry fields, radio buttons, and 
check boxes. Figure 11(Bottom): The THTMLWriter's template 
document feature was used to create this page. 
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HTML 2.0 Reference http://www.w3.org/hypertext/(WWW/MarkUp/html-spec/html-spec_toc.html 
HTML 3.0 Reference http://www.w3.org/hypertext/(WWW/MarkUp/html3/Contents.html 


Netscape Extensions 


Microsoft Internet 
Explorer Extensions 


http://www.netscape.com/assist/net_sites/html_extensions.html 


http://www. microsoft.com/intdev/browser/iexplore.htm 


HTML Tutorial http://www.utirc.utoronto.ca/HTMLdocs/NewHTML/htmlindex.html 


http://hoohoo.ncsa.uiuc.edu/cgi/ 


WinCGI 


hitp://www.city.net/win-httpd/httpddoc/wincgi.htm 


hitp://www.talentcom.com/iview.htm 
THtmlViewer Component hitp://www.empire.net/~dbaldwin/ 


Figure 12: HTML-related references available on the Internet. 


current date and time and a random number between 1 
and 100. A second document is included in the first, 
showing how common sections can be maintained in 
one spot only and used in many documents as required. 


(Note that the demonstration program runs best outside 
the Delphi IDE. Otherwise, exceptions that are trapped 
internally appear and disrupt the flow of the program.) 


Conclusion 

The THTMLWriter component allows us to generate 
HTML on-the-fly. It provides access to most of the fea- 
tures of the various HTML versions, along with many 
Netscape and some Microsoft Internet Explorer exten- 
sions. It detects many errors and warns us of possible 
problems while generating our pages. 





Combine TH7MLWviter with a CGI component and you 
have a Web site just waiting to happen. All from our 
familiar Delphi environment.A 


The THT MLWyiter component and demonstration project 
referenced in this article are available on the Delphi 
Informant Works CD located in INFORM\96\MAY\- 
DI9GO5KW. 


Keith Wood is an analyst/programmer with CSC Australia, based in Canberra. He 
started using Borland’s products with Turbo Pascal on a CP/M machine. Although 
not working with Delphi currently he has enjoyed exploring if since it first 
appeared. You an reach him via e-mail at kwood@nla.gov.au or by phone 
(Australia) 6 291 8070. 
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